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INTRODUCTION 


In  order  to  perform  behavioral  studies  relating  to  text 
processing  applications  it  is  necessary  to  have  an  editor  that 
can  be  configured  quickly  for  specialized  experiments.  Since 
most  editors  are  inherently  complicated,  an  organization  is 
needed  that  experimenters  can  modify  for  behavioral  studies 
without  extensive  programming  experience.  The  result  was  an 
editor  called  SAM,  which  is  a  context  oriented  line  editor  with  a 
number  of  novel  features  and  creature  comforts  that  computer 
people  are  not  used  to  seeing  on  an  editor.  Some  of  these  ideas 
come  from  years  of  discussion,  others  come  from  existing  editors, 
and  yet  others  had  their  origins  in  an  editing/human  factors 
seminar  held  in  the  Computer  Science  Department  at  Virginia  Tech 
in  the  spring  of  1980.  Thus,  SAM  has  some  novel  features,  both 
in  its  external  behavior  and  in  its  internal  structure. 

Appearance 

One  of  SAM's  most  novel  features  is  a  queue,  which  is  the 
mechanism  by  means  of  which  lines  may  be  moved  around  from 
location  to  location  within  a  file  or  between  files.  SAM  allows 
a  user  to  open  two  files,  called  the  PRIMARY  and  SECONDARY  files, 
and  the  SWITCH  command  allows  the  user  to  flip  back  and  forth 
between  the  two  files.  The  queue  is  the  means  of  transferring 
lines  from  one  file  to  another,  and  with  the  queue  one  can 
accomplish  such  tasks  as  reversing  line  order  and  reordering 
sections  of  text  in  arbitrary  order. 
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SAM  allows  ths  user  to  edit  syntactically  Incorrect 
commands,  and  most  of  the  command  operands  are  generalized  to 
function  upward  or  downward  by  supplying  a  signed  operand.  In 
the  case  of  string  operands,  a  single  space  or  sign  after  the 
command  name  acts  as  the  string  delimeter.  All  commands, 
switches,  and  switch  states  can  be  specified  by  typing  a  unique 
prefix,  and  underscores  may  be  used  to  separate  multi-word 
commands . 

SAM  does  not  allow  a  user  to  type  operands  for  commands  that 
are  incorrect.  In  fact,  the  user  is  warned  aurally  of  erroneous 
input,  and  the  number  of  bells  heard  is  proportional  to  the 
severity  of  the  error.  If  the  command  is  correct  but  the  operand 
is  erroneous,  the  user  is  warned  and  is  asked  to  complete  the 
operand  from  the  point  where  the  erroneous  input  occurred.  On 
the  other  hand,  every  effort  is  made  to  make  sense  of  the  user's 
input. 

SAM  i^  intended  as  a  programming  tool,  although  some  may 
find  its  features  amenable  to  certain  text  processing 
applications  as  well.  The  user  is  urged  to  make  use  of  relative 
movements  in  locating  information  to  be  edited.  Although  it  is 
easy  to  determine  absolute  line  numbers  and  locate  information  by 
absolute  addressing,  the  command  structure  is  designed  to 
minimize  the  use  of  absolute  addressing. 
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Internals 


SAM  has  8300  lines  of  code,  mostly  FORTRAN  77,  in  55 
modules.  Of  these,  the  main  storage  system  is  manipulated  with 
only  3  procedures  -  INSERT,  DELETE,  and  NEXT.  All  messages  are 
produced  by  one  subroutine,  and  two  subroutines  -  CPARSER  and 
SPARSER,  are  responsible  for  all  command  and  operand  keywords. 
These  are  automatic  completion  algorithms  that  allow  an 
experimenter  to  add,  delete,  and  modify  names  simply  by  inserting 
them  into  alphabetized  tables.  Two  subroutines  -  COMMAND  and 
STORE  -  take  care  of  the  detailed  handling  of  individual 
characters  in  edit  and  input  mode.  Finally,  there  are  11  modular 
parsers  that  plug  into  the  code  as  needed  to  decode  individual 
operands.  These  are  table  driven  so  that  they  may  easily  be 
modified  by  altering  state  transition  tables.  The  reBt  of  SAM 
consists  of  the  code  necessary  to  communicate  with  the  user's 
terminal  open  and  close  files,  and  perform  the  actual  editing 
functions. 


In  order  to  specialize  SAM  for  an  experiment,  the  experiment 
designer 

1}  Inserts  the  command  names  into  an  alphabetized  list  in 
CPARSEP. . 

2)  Selects  the  appropriate  operand  parser  for  each  command 
from  those  provided  (or  modifies  some  of  the  existing 
parsers) . 

3)  Selects  the  semantic  routine  for  each  command  that 
actually  performs  the  editing  function.  Functions  not 
provided  by  SAM  muBt  be  added,  and  this  requires  on  the 
average  about  50  lines  of  code  per  new  command. 

4)  Decides  what  should  be  metered  and  inserts  calls  to  the 
metering  procedure  in  appropriate  places. 
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The  time  required  to  modify  SAM  varies  from  a  faw  hours  for 
simple  command  renaming  or  elimination  to  a  week  or  two  if  new 
commands  are  to  be  designed. 


USING  NATIVE  SAM 


Input  mode 

CR  The  standard  line  terminator.  When  the  cursor  is  at  the  left 
margin,  it  causes  a  mode  change  to  edit  mode. 

LF  Line  terminator  ($J  on  terminals  without  LF) . 

ESC  Escape  character  preceding  any  character  except  those  trapped 
by  VMS  will  cause  that  character  to  be  entered  as  input. 

Command  mode 

There  are  two  classes  of  commands  -  Immediate  commands  and 
standard  commands.  Immediate  commands  are  single  character 
commands  that  are  executed  immediately  when  a  key  iu  struck  at 
the  beginning  of  a  new  line.  There  are  6  immediate  commands: 

.  Type  the  the  current  line. 

#  Type  the  number  of  the  current  line. 

+  Move  the  line  pointer  to  the  next  line  and  echo  this  line. 

-  Move  the  line  pointer  to  the  previous  line  and  echo  this 
line. 

?  Type  the  default  help  for  SAM 

CR  Switch  between  edit  and  input  modes  and  give  a  bell  signal. 
There  are  31  standard  commands,  and  several  of  these  have 
synonyms.  In  the  following  table,  capital  letters  denote  minimal 
prefixes,  and  underscores  may  or  may  not  be  used  as  punctuation, 
as  desired. 


=,  REPEat 
ANchor 
A,  ARea 
APpend 

C ,  CHange 

CQ,  CLear_queue 
Combine 

D,  DELETE 

DS,  DELETE_To_scring 
EL,  EDit_line 
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File 

GS,  GEt  secondary 

HELp 

HEX 

Locate 

Next 

PD,  POP_And  delete 
POP 

Q,  queue 

QD,  QUEUE_And_de 1 e t e 

QUIt 

RETurn 

R,  REPLace 

S,  SWitch 
SAve 

SEt 

SPlit 

STatus 

T,  TYPE 

TQ,  TYPE_Queue 

nnn  (Set  pointer  to  line  nnn) 

Command  Completion 

Whenever  a  unique  command  prefix  is  detected,  the  command  is 
completed  automatically.  The  user  need  not  be  aware  of  this, 
since  if  the  rest  of  the  command  is  typed  after  completion,  the 
extra  characters  are  ignored. 


Character  Sat 

Six  characters  are  trapped  by  the  VAX  terminal  driver,  and 


these  characters  have  the  normal  VAX  functions.  These  are 


CNTRL 

C 

ETX 

CNTRL 

0 

SI 

CNTRL 

Q 

DC1 

CNTRL 

S 

DC3 

CNTRL 

X 

CAN 

CNTRL 

Y 

EM 

(Returns  control  to  the  command  processor) 
(Cancels  the  current  output  operation) 
(XON=Resume  output) 

(XOFF=Suspend  output) 

(Cancels  any  read  and  purges  type-ahead) 
(Returns  control  to  the  command  processor) 


In  addition,  the  editor  uses  the  following  characters. 


CR  (Line  terminator) 
CNTRL  U  NAK  (Line  delete) 

DEL  (Character  delete) 
BS  (Character  delete) 
ESC  (Escape) 
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TAB  (Horizontal  tabs) 

CNTRL  J  LF  (Line  terminator) 

Any  of  these  last  7  characters  can  be  inserted  into  a  line  by 

preceding  the  character  by  ESC.  In  addition  to  the  above 

characters,  *  is  used  to  represent  numerical  infinity  wherever 


the  context,  makes  sense. 


Tabs 


SAM  has  two  types  of  tab  stops,  setable  with  the  SET 
command.  Pseudo  tabs  cause  echoing  of  SP  characters  and 
insertion  of  SP  characters  into  the  text  file.  This  feature 
facilitates  indentation  of  programs.  True  tabs  cause  echoing  of 
SP  characters  and  insertion  of  HT  into  the  text  file. 

Command  pre-parsing 

In  edit  mode,  SAM  checks  for  command  validity  as  soon  as  a 
command  is  typed.  If  a  command  is  invalid,  two  bells  are  given, 
and  further  typing  is  blocked.  The  user  may  backspace  to  make 
corrections  or  cancel  the  line.  Valid  commands: 

1)  May  be  preceded  by  non-printing  characters 

2)  Must  not  contain  spaces 

3)  May  contain  underscores  for  clarity 

4)  Must  be  a  complete  command  or  an  unambiguous  prefix 

5)  Must  be  followed  by  a  non-digit  if  the  command  is  a  number 

6)  Must  be  followed  bv  a  non-letter  if  the  command  is  a 
character  string 

Startup  Command  File 

SAM  has  the  capability  for  executing  a  startup  command  file 
when  an  editing  session  begins.  This  command  file  is  executed 
just  before  SAM  types  EDIT  or  INPUT  after  the  editor  is  invoked. 
When  SAM  is  invoked,  it  searches  the  logical  name  tablee  in  VMS 
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for  the  name,  START_SAM.  If  this  name  is  present,  its 
translation  is  interpreted  to  be  the  name  of  the  command  file  to 
be  executed.  As  an  example,  suppose  that  init.sam  was  the 
command  file  to  be  executed.  Then,  the  logical  name  assignment 
is  made  by  typing  the  VMS  command 

ASSIGN  init.sam  START_SAM 

Equivalently,  this  VMS  command  can  be  placed  in  the  user's 
login. com. 

All  SAM  commands  can  be  executed  by  typing  them  in  a  file,  one 
command  per  line.  Any  command  line  with  improper  syntax  will  be 
skipped. 
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COMMAND  SUMMARY 


=,  REPEat 

Repeats  the  most  recent  successful  command.  Immediate 
commands  cannot  be  repeated  by  using  the  repeat  command. 

A,  ARea  {  N  |  *  } 

Displays  the  context  of  +N  lines  around  the  current  line.  If 
N  is  omitted,  a  default  value  dependent  upon  the  terminal 
data  rate  is  selected.  The  current  line  is  unchanged. 


ANchor 

The  location  of  the  current  line  is  saved  by  the  editor.  No 
matter  what  changes  are  made  in  the  file,  the  RETURN  command 
will  return  the  editor  to  the  anchored  line  unless  i-!  has 
been  deleted. 


APpend  {  STRING  J 

If  no  string  is  given,  places  the  cursor  at  the  end  of  the 
current  line  and  enters  temporary  input  mode.  If  a  string  is 
specified  it  is  appended  to  the  current  line. 


C,  CHange  {  +  |  -  |  ,N  |  +N  |  -N  |  *  |  +*  |  -*  j  (  D  SI  {  D  S2  { 

D  }}] 

On  N  lines,  including  the  current  line,  replace  string  SI 
with  S2.  The  delimeter,  D,  may  be  any  printing  character 
that  does  not  appear  in  either  SI  or  S2.  The  changes  are 
made  for  the  first,  last,  or  all  occurrences  of  SI,  depending 
upon  the  setting  of  the  change  switch.  The  current  line 
remains  the  same.  The  default  is  to  change  1  line. 

CQ,  CLear_queue  {  N  |  *  } 

Clears  the  queue  of  the  specified  number  of  lines.  If  no  N 
is  specified,  the  entire  queue  is  cleared. 

Combine 

Appends  the  next  lire  to  the  current  line  and  replaces  both 
by  the  single  new  line.  The  current  line  becomes  the  new 
line. 

D,  DELETE  {  +  |  -  |  N  |  +N  |  -N  |  *  |  r*  |  -*  } 

Deletes  a  specified  set  of  lines  including  the  current  line. 
The  current  line  becomes  the  next  undeleted  line  in  the 
direction  of  the  deletions.  The  default  is  1. 
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DS,  DE LETE_To_ string  [  STRING  |  + STRING  |  -STRING  ) 

Deletes  lines,  including  the  current  line  up  to  but  not 
including  the  first  line  containing  STRING.  The  command  has 
no  effect  if  no  line  containing  STRING  is  found.  Otherwise 
the  current  line  becomes  the  one  that  contains  STRING.  The 
only  characters  that  may  precede  STRING  are  a  single  SP,  a 
sign,  or  a  SP  and  a  sign. 

EL,  EDit_line 

Enters  a  special  editing  mode  for  the  current  line.  Space  to 

the  point  where  a  change  is  desired.  Then  type: 

C  -  Change  current  character  and  advance 
CR  -  Terminate  edit  line  mode 
D  -  Delete  current  character  and  advance 
I  -  Insert  string  before  next  character 
R  -  Reverse  the  case  of  current  character  and  advance 
CU  -  Re-edit  the  current  line 

File  {  +  |  FILENAME  |  +FILENAME  } 

Files  the  primary  file  aid  terminates  the  editor.  If  no 
FILENAME  is  specified  the  current  file  name  is  used.  A  new 
version  number  is  generated  if  the  +  symbol  is  specified. 


GS,  GEt_secondary  (  FILENAME  ] 

Opens  the  named  secondary  file  for  editing.  Any  previously 
opened  secondary  file  is  eliminated  from  SAM's  internal 
storage  without  writing  it  back  out  to  permanent  storage. 
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The  secondary  file  can  be  stored  permanently  only  by  using 
the  SAVE  command. 


HELp  {  COMMAND  j 

Types  out  a  command  list  or  provides  help  on  a  command  if  one 
is  specified.  If  help  is  requested  after  making  an  error  in 
a  command  operand,  help  will  default  to  the  help  for  that 
command.  Help  on  SET  command  switches  is  available  by 
typing,  HELP  SET  <switch>. 

HEX  {  MNEMONIC  |  hh  }  ddd  } 

If  no  operand  is  specified,  the  ASCII  mnemonics  for  the 
characters  in  the  current  line  are  given.  If  the  operand  is 
an  ASCII  mnemonic,  a  2  digit  hex  number,  or  a  3  digit  decimal 
number,  all  3  representations  are  returned.  If  the  character 
is  a  control  character,  the  terminal  control  code  is  also 
returned . 


Locate  [  STRING  |  + STRING  |  -STRING  ] 

Locates  the  first  line  containing  the  specified  string. 
There  is  no  effect  if  the  string  is  not  found.  The  only 
characters  that  may  precede  STRING  are  a  single  SP,  a  sign, 
or  a  SP  and  a  sign.  The  number  of  lines  traversed  in 
locating  the  desired  line  is  printed  on  the  terminal. 


Next  {  +  |  -  |  N  |  +N  |  -N  |  *  |  +*  |  -*  } 

Moves  the  current  line  pointer  N  lines  in  the  specified 
direction.  The  default  is  1. 
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PD,  POP_And_delete  {  +  |  -  |  N  |  +N  |  -N  |  *  |  +*  |  -*  } 

Pops  the  specified  number  of  lines  from  the  queue  into  the 
text  after  the  current  line  and  deletes  the  popped  lines  from 
the  queue.  The  current  line  is  the  last  one  popped  from  the 
queue.  The  default  is  1.  Upward  pops  will  result  in 
reversed  line  order. 


POP  {  +  |  -  |  N  |  +N  |  -U  |  *  |  +*  |  -*  } 

Pops  the  specified  number  of  lines  from  the  queue  into  the 
text  after  the  current  line.  The  current  line  is  the  last 
one  popped  from  the  queue.  The  default  is  1.  Upward  pops 
will  result  in  reversed  line  order. 


Q,  QUEUE  {  +  |  -  |  N  |  +N  |  -N  |  *  |  +*  |  -*  ) 

Places  the  specified  number  of  lines,  starting  with  the 
current  line,  onto  the  queue.  The  current  line  becomes  the 
line  following  the  las*  one  placed  on  the  qu*»’ie.  The  default 
is  1. 


QD,  QUEUE_And_de 1 e te  [  +  |  -  |  N  |  +N  |  -N  |  *  |  +*  |  -*  } 

Places  the  specified  number  of  lines,  starting  with  the 
current  line,  onto  the  queue  and  deletes  them  from  the  text. 
The  current  line  becomes  the  one  after  the  last  one  deleted 
in  the  direction  of  the  deletion.  The  default  is  1. 


QUIt 


Leave  tha  editor  without  writing  files  to  permanent  storage. 
If  changes  have  been  made,  the  user  is  asked  to  verify  the 
request. 


RETurn 

Makes  the  editor  return  to  the  anchored  line.  The  number  of 
lines  traversed  in  returning  to  the  anchored  line  is  printed 
on  the  terminal. 


R,  REPLace  {  +  |  -  |  N  |  +N  |  -N  |  *  |  +*  |  -*  } 

Deletes  the  specified  lines,  starting  with  the  current  line 
and  enters  input  mode.  If  the  deletion  was  an  upward 
deletion,  the  inserted  lines  go  above  the  current  line.  The 
current  line  becomes  the  last  inserted  line.  The  default  is 
1. 

S,  switch 

The  editing  environment  is  toggled  back  and  forth  between  the 
PkIMARY  and  SECONDARY  files. 
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SAve  j  +  |  FILENAME  |  ^FILENAME  ) 

Files  the  current  working  file  (PRIMARY  or  SECONDARY).  If  no 
FILENAME  is  specified  the  current  file  name  is  used.  A  new 
version  number  is  generated  if  the  +  symbol  is  specified. 
The  current  file  name  will  become  the  name  of  the  file  just 
written. 


SEt  [  SWITCH  {  STATE  }  |  SWITCH  {  LIST  j  ] 

Allows  the  user  to  alter  the  internal  behavior  of  the  editor. 
A  LIST  is  a  sequence  of  numbers  separated  by  SPACES.  If  a 
number  or  state  is  omitted,  the  editor  default  value  is  used. 
The  SWITCHes  and  their  STATES  are 


ANsi^taias  Sets  tabs  in  every  8  columns. 

ARea  {  nnn  }  Sets  the  default  context  for  the  ARea  command. 

Bells  {  on  |  off  J  Sets  audible  notification  of  syntactic 
errors. 

CHange  {  first  |  last  |  all  }  Affects  the  CHange  command. 
CLear_tabs  {  LIST  j  Clears  tabs  at  specified  locations. 
COnvert_tabs  {  on  |  off  }  Sets  echo  of  true  tabs  to  SP 
characters. 

Def ault_tabs  {  nnn  |  Tab  in  column  9  and  pseudo  tabs  every  nnn. 
First_c°lumn  {  nnn  }  Sets  the  first  column  for  editing  commands. 
«a*d_c°py  {  on  |  off  }  Sets  echoing  for  hard  copy  terminals. 
LAst_column  {  nnn  j  Sets  the  last  column  for  editing  commands. 
Line_length  {  nnn  }  Sets  the  maximum  line  length  for  files. 
PArenthesis_count  j  on  |  off  j  Sets  paren  counting  in  input  mode. 
PSeudO--tabB  I  LIST  }  Sets  pseudo  tabs  at  specified  positions. 
Screen_width  {  nnn  }  Sets  the  terminal  line  length. 

J™8  {  LI?T  *  Sets  true  tab  stoPs  at  specified  positions. 

TEk  {  on  |  off  }  Sets  screen  handling  for  Tektronix  terminals. 
upper_case  {  on  |  off  }  Sets  conversion  to  upper  case. 
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SPlit  {  STRING  } 

Splits  the  currsnt  line  into  two  linos  using  the  cursor  if 
STRING  is  not  specified  or  before  STRING  if  STRING  is 
specified.  The  current  line  will  be  the  second  part  of  the 
split  line.  The  only  character  that  can  precede  STRING  is  a 
single  SP. 

STatus 

Displays  current  file  names,  identifies  the  working  file, 
prints  the  current  file  lengths,  and  displays  the  state  of 
the  editing  switches. 

T,  TYPE  {  N  |  *  } 

Types  on  the  screen  the  specified  lines,  starting  with  the 
current  line.  The  current  line  is  the  last  one  typed.  The 
default  is  1. 

TQ,  TYPE_Queue  {  N  |  *  } 

Types  on  the  screen  the  specified  lines  from  the  queue.  The 
default  is  1. 

N 

Sets  the  line  pointer  to  the  line  whose  current  line  number 
is  N.  0  is  the  empty  line  above  the  file,  and  *  is  the  empty 
line  below  the  file,  since  *  represents  numerical  infinity. 
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SAM’s  STORAGE  SYSTEM 


Although  numerous  procedures  support  SAM's  storage  system, 
only  three  are  used  to  enter  or  retrieve  information.  These  are 

INSERT  (direction) 

NEXT  ( status , increment ) 

DELETE  (status, increment) 

where  status  is  a  byte  that  determines  when  the  line  pointer  is 
at  the  top  or  bottom  of  the  file  and  the  other  variables  are  of 
type  *2 . 

INSERT  requires  that  the  line  to  be  inserted  is  in  the 
global  array,  input_buf fer ,  and  that  icnt,  the  line  length,  be 
set  to  the  line  length.  NEXT  and  DELETE  return  the  current  line 
to  the  input_buffer .  The  arguments  can  be  positive  or  negative, 
and  it  is  not  possible  to  alter  or  delete  the  two  special  lines, 
TOF:  end  BOFs  that  are  always  present  in  the  file. 

The  storage  system  itself  is  a  virtual  storage  system  that 
consists  of  three  data  structures  --  the  page  tables,  working 
storage  for  both  primary  and  secondary  files,  and  a  queue.  Upon 
entering  SAM  a  delay  is  observed  as  the  files  are  opened  and  as 
the  source  files  are  moved  into  the  storage  system.  Once  in  the 
storage  system,  files  can  be  edited  very  quickly.  Source  files 
are  closed  as  soon  as  the  storage  system  has  been  loaded,  and  the 
only  opon  files  are  SAM  internal  files.  If  the  system  crashes  or 
if  the  user  exits  with  a  <:Y,  the  internal  files  remain  intact  and 
current  up  to  the  last  time  the  editor  paged.  Upon  reentry,  SAM 
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notices  the  presence  of  these  undeleted  internal  files  end  ssks 
the  user  if  he  wishes  to  recover  them. 


SAM  requires  a  minimum  of  18  pages  of  disk  storage  and  at 
least  36  pages  if  both  primary  and  secondary  files  are  to  be 
used. 


The  Page  Table 


The  page  table  is  a  physically  sequential  list  of  the 

numbers  of  the  pages  of  working  storage.  Each  entry  is  a  *2  page 

number,  and  a  0  byte  separates  currently  allocated  pages  from 

free  pages.  A  number  of  procedures  are  provided  for  entering  and 

accessing  information  in  the  page  table.  These  are: 

READ_PT  (n) 

WRITE_PT  (n) 

INITJPT  (n) 

QUERY  PT  ( status, code, n, logical, physical, length) 
ENTER'PT  (n, length) 

S I 2E_PT  (n, begin, current, end, total) 

RESTORE_PT  (n) 

EXPAND_PT  ( status, n, physical) 

SHRINK_PT  (n, pages) 

READ  WORK  (n,page) 

WRITE_WORK  (n, page) 

Page  Contents 


Each  page  of  working  storage  consists  of  109  24-byte 
fragments.  Each  text  line  occupies  several  fragments,  depending 
upon  its  length.  Each  fragment  has  a  *2  length  field  and  both 
forward  and  backward  pointers.  The  length  field  of  the  first 
fragment  of  a  line  contains  the  lina  length,  and  other  fragments 
of  a  line  have  a  length  field  containing  -1.  The  backward 
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pointer  of  the  first  fragment  of  the  first  line  of  a  page  and  the 

forward  pointer  of  the  last  fragment  of  the  last  line  of  a  page 

contain  0.  No  page  in  the  storage  system  may  be  entirely  empty. 

Also  stored  with  each  page  are  the  following  *2  variables: 

fline  -  Pointer  to  the  first  fragment  of  the  first  line 
ffree  -  Pointer  to  the  free  space  list 
nlines  -  The  number  of  lines  in  the  page 
nfree  -  The  number  of  free  fragments 

lline  -  Pointer  to  the  first  fragment  of  the  last  line 
In  addition  to  the  variables  above  associated  with  a  page,  there 
are  other  global  variables  that  contain  important  information. 
These  include: 

cfile  -  The  number  of  the  currently  active  file 
cfrag  -  Pointer  to  the  first  fragment  of  the  current  line 
cptr  -  The  number  of  the  current  line  in  the  page 
cline  -  The  number  of  the  current  line  in  the  file 

Paging 

When  an  insertion  is  attempted  in  a  page  that  is  full,  a 
procedure  called  SPLIT  removes  several  lines  f;  om  the  current 
page,  including  the  current  line,  and  places  them  in  a  new  page. 
The  new  page  will  contain  between  10%  and  50%  of  the  lines  from 
the  old  page.  The  advantage  of  the  page  table  is  that  a  line  can 
be  retrieved  quickly  from  any  location  in  the  file  s.nd  that 
deletions  are  also  very  fast,  no  matter  how  many  lines  are 
deleted.  In  the  first  implementation  there  is  no  provision  for 
merging  pages  that  have  low  occupancy.  Under  the  assumptions 
that  lines  occupy  an  average  of  two  fragments  and  assuming  75% 
page  occupancy,  the  storage  system  will  hold  32,767  lines,  which 
is  the  address  space  of  the  editor. 
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The  page  tables  for  both  the  primary  and  secondary  files 
consist  of  single  1534  byte  records,  and  working  storage  has  up 
to  766  pages  of  3071  bytes  for  each  file.  Working  storage  makes 
use  of  direct  access  so  that  pages  may  be  located  without  reading 
through  the  entire  file. 

File  Recovery 

SAM's  internal  working  files  are  deleted  upon  normal  exit 
from  the  editor.  Should  the  system  crash  or  should  the  user 
inadvertently  leave  SAM  by  typing  <:Y,  the  internal  files  are  not 
deleted.  Upon  reentry  into  SAM,  if  these  files  are  present,  SAM 
will  ask  whether  the  user  wishes  to  continue  editing  them.  The 
user  should  respond  with  an  immediate  subcommand,  y  or  n.  The 
working  files  are  updated  only  when  the  editor  pages.  Normally 
the  SAVE  command  would  be  used  if  the  user  wishes  to  guarantee 
the  currency  of  the  work,  though  SAM  can  be  forced  to  page  by 
typing  the  SWITCH  command. 

I/O  Services 

All  of  SAM's  i/o  services  are  provided  through  assembly 
language  subprograms  that  call  the  VAX  Record  Management  System. 
The  lowest  level  procedures  are: 

EXPAND_FNAME 

OPENER 

CLOSER 

READ_SRC 

WRITE_SRC 

PAGE 10 

STACK 
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SAM  ignores  all  fixed  control  fields  of  text  input  files, 
but  it  writes  sequentially  numbered  fixed  control  fields  into  its 
output  files.  The  fixed  control  accounts  for  the  sequential 
statement  numbers  that  appear  when  a  SAM-edited  file  is  printed. 


SAM's  COMMAND  ANALYZER 


Parsers 


SAM  has  13  modular  parsers,  2  of  which  are  table-driven 

keyword  analyzers  and  the  remainder  of  which  are  finite  state 

parsers.  The  keyword  analyzers  are 

C_PARSER 

S_PARSER 

and  the  operand  parsers  are 

CHANGE 

EMPTY 

FILE 

HEX 

NUMBER 
POS_NUMBER 
S I GNED_NUMBER 
SIGNED_FILE 
STRING 

S I GNED_STR I NG 
SWITCH 


The  operand  parsers  are  adequate  for  parsing  all  command 
operands,  and  if  new  commands  are  created,  these  parsers  can  be 
used.  C_PARSER  and  SPARSER  are  used  to  decode  command  names  and 
switches,  respectively,  on  the  basis  of  unique  prefix.  New 
command  names  or  switches  can  be  added  Eiimply  by  including  them 
in  alphabetized  tables. 


Syntax 


One  of  the  most  difficult  aspects  of  the  design  of  SAM's 
syntax  was  determining  a  rule  for  delimiting  a  string.  Except  in 
the  CHANGE  command  where  string  delimiters  are  printing 
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characters,  a  string  operand  is  delimited  from  preceding 
characters  by  a  single  space.  Also,  if  it  makes  sense,  other 
implied  delimiters  can  be  used.  For  example,  L90  makes  sense 
because  9  is  not  part  of  any  command  containing  characters? 
therefore  9  must  be  the  first  character  of  the  operand  string  for 
the  LOCATE  command.  Lab,  however,  appears  to  the  syntax  analyzer 
as  an  invalid  command. 
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SAM's  SCREEN  HANDLER 


SAM's  charactar  handling  is  one  of  its  most  important 
features,  and  SAM  relies  heavily  upon  full  duplex  communications. 
SAM  interprets  characters  one  by  one  as  they  are  typed,  and  the 
response  to  each  character  is  computed  individually.  While  SAM 
has  been  implemented  to  be  terminal  independent,  three  broad 
classes  of  terminals  -  scrolling  CRT's,  non-scrolling  but  paged 
terminals,  and  hardcopy  terminals  -  are  supported.  Two 
procedures  do  most  of  SAM's  character  interpretation: 


STORE 

COMMAND 

STORE  does  character  handling  for  input  mode,  and  COMMAND  does 

character  handling  in  edit  mode.  These  procedures  are  supported 

by  three  bottom  level  i/o  procedures 

PUT_CHARS 

XMITCHARS 

GET_CHARS 

and  the  following  service  procedures 

ECHO 

SCREEN 

TYPE_LINE 

MSG 

NEXTJTAB 
TYPE  NUMBER 
UPPER 
QUIT 
CLASS 

In  input  mode,  each  character  is  interpreted,  echoed,  and  stored 
as  necessary  ir  the  input  buffer  by  STORE.  In  addition,  STORE 
keeps  track  of  i:he  physical  location  of  each  character  on  the 
screen  so  that  it  knows  how  to  backspace  over  tabs  and  so  that  if 
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physical  screen  wraparound  occurs,  the  screen  line  count  can  be 
updated.  When  SAM  is  called  it  sends  an  escape  sequence  to  test 
for  a  Tektronix  4012/13  display.  If  the  display  is  a  Tektronix, 
SAM  remembers  the  fact  and  does  special  screen  handling,  since 
the  Tektronix  will  not  scroll.  If  hardcopy  or  Tektronix  mode  is 
set,  prompting  and  backspace  handling  change  since  no  selective 
erase  is  possible  on  such  terminals.  Also,  in  Tektronix  mode, 
each  time  the  screen  is  cleared,  a  dither  in  the  range  0  to  19  is 
subtracted  randomly  from  the  cursor's  verv?cal  home  position  to 
reduce  screen  degeneration. 

In  edit  mode,  character  handling  changes  slightly.  Every 
nonprinting  character  in  the  command  input  buffer  is  echoed  as  a 
SP  character  so  that  the  user  can  tell  exactly  how  many 
characters  are  in  the  buffer.  As  characters  are  typed,  C_PARSER 
attempts  to  locate  the  end  of  the  command.  When  it  does,  if  the 
command  is  ambiguous  or  in  error,  the  uaer  is  notified  and,  in 
the  latter  case,  prevented  from  further  typing.  If  the  command 
is  correct,  no  further  parsing  occurs  until  the  line  is  complete. 
If  the  operand  parser  finds  an  error,  the  command  line  is 
rewritten  up  to  the  point  where  the  error  was  detected  so  that 
the  user  can  correct  the  command. 

All  user  messages  are  transmitted  to  the  terminal  by  the  MSG 
subroutine.  Thus,  it  is  straightforward  to  change  the 
communication  from  SAM  to  the  user. 
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Screen  clearing  and  special  functions  are  provided  by  the 
SCREEN  subroutine  which,  for  the  Tektronix,  checks  the  line  count 
each  time  it  is  called  to  determine  whether  there  is  space  on  the 
screen  for  the  next  line.  Since  ECHO  is  the  only  procedure  in 
SAM  to  echo  linefeed  characters,  ECHO  is  chiefly  responsible  for 
counting  lines.  STORE,  COMMAND,  and  TYPE_LINE  also  increment  the 
line  count  if  physical  wraparound  occurs,  since  they  keep  track 
of  screen  location.  TYPE_LINE  has  principal  responsibility  for 
calling  SCREEN  to  test  for  available  screen  space.  SCREEN  must 
be  called  directly  at  all  other  points  in  SAM  where  output  is 
sent  to  the  screen  with  other  output  services. 
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